home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kprinter.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  25.5 KB  |  781 lines
  1. /*
  2.  *  This file is part of the KDE libraries
  3.  *  Copyright (c) 2001 Michael Goffioul <kdeprint@swing.be>
  4.  *
  5.  *
  6.  *  This library is free software; you can redistribute it and/or
  7.  *  modify it under the terms of the GNU Library General Public
  8.  *  License version 2 as published by the Free Software Foundation.
  9.  *
  10.  *  This library is distributed in the hope that it will be useful,
  11.  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  12.  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13.  *  Library General Public License for more details.
  14.  *
  15.  *  You should have received a copy of the GNU Library General Public License
  16.  *  along with this library; see the file COPYING.LIB.  If not, write to
  17.  *  the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18.  *  Boston, MA 02110-1301, USA.
  19.  **/
  20.  
  21. #ifndef KPRINTER_H
  22. #define KPRINTER_H
  23.  
  24. #include <qpaintdevice.h>
  25. #include <qprinter.h>
  26. #include <qmap.h>
  27. #include <qstring.h>
  28. #include <qstringlist.h>
  29. #include <qvaluelist.h>
  30. #include <kdemacros.h>
  31. #include <kdelibs_export.h>
  32.  
  33. #include <kdeprint/kpreloadobject.h>
  34.  
  35. class KPrinterImpl;
  36. class KPrintDialogPage;
  37. class KPrinterPrivate;
  38. class DrPageSize;
  39.  
  40. /**
  41.  * This class is the main interface to access the KDE print framework. It allows KDE
  42.  * applications to easily access the print system, through an interface that is compatible
  43.  * with QPrinter. So that the porting of an existing application should be as easy as
  44.  * replacing any occurrence of QPrinter by KPrinter. However applications that explicitly
  45.  * used the QPrintDialog class must be changed to the standard KPrinter way of accessing
  46.  * the print dialog.
  47.  *
  48.  * Basically, a KDE application will use the KPrinter object as a paint device, and will draw
  49.  * on it using QPainter. In a standard application, the use of the KPrinter class will
  50.  * look like this:
  51.  * \code
  52.  * #include <kprinter.h>
  53.  * #include <qpainter.h>
  54.  *
  55.  * void MyClass::doPrint()
  56.  * {
  57.  *   KPrinter printer;
  58.  *
  59.  *   // do some printer initialization
  60.  *   printer.setFullPage( true );
  61.  *
  62.  *   // initialize the printer using the print dialog
  63.  *   if ( printer.setup( this ) )
  64.  *   {
  65.  *     // create a painter to paint on the printer object
  66.  *     QPainter painter;
  67.  *
  68.  *     // start painting
  69.  *     painter.begin( &printer );
  70.  *     <do something>
  71.  *     // stop painting, this will automatically send the print data to the printer
  72.  *     painter.end();
  73.  *   }
  74.  * }
  75.  * \endcode
  76.  *
  77.  * The KPrinter interface also allows some more advanced possibilities, like the customization
  78.  * of the print dialog to integrate application specific print options. This is done by subclassing
  79.  * KPrintDialogPage and adding the page using addDialogPage().
  80.  *
  81.  * When compiling an application that uses KPrinter, you must link to -lkdeprint, which when
  82.  * using the standard KDE build framework can be done by adding $(LIB_KDEPRINT) to _LDADD.
  83.  *
  84.  * @short The central interface class to access the KDE print system.
  85.  * @author Michael Goffioul
  86.  * @see QPrinter, KPrintDialogPage
  87.  */
  88. class KDEPRINT_EXPORT KPrinter : public QPaintDevice, public KPReloadObject
  89. {
  90. friend class KPrinterWrapper;
  91. friend class KPrinterImpl;
  92. public:
  93.     // Print global settings (set via static functions)
  94.     /**
  95.      * Defines the standard pages available for the print dialog:
  96.      *  @li @p CopiesPage: page and copies selection (included by default)
  97.      *  @li @p FilesPage: file selection (only used by kprinter utility)
  98.      *  @li @p Custom: unused
  99.      *
  100.      * @see addStandardPage(), removeStandardPage()
  101.      */
  102.     enum StandardPageType { CopiesPage = 0x01, FilesPage = 0x02, Custom = 0x10 };
  103.     /**
  104.      * Defines whether the application can perform page selection itself or not.
  105.      * Some print systems (like CUPS) can do page selection, in this case the
  106.      * page selection will be enabled in the print dialog, otherwise it will be
  107.      * disabled. However some applications (word processor) can do page selection
  108.      * themselves, then it will be enabled in the print dialog, whatever the
  109.      * print system used. But such an application has to tell kdeprint about its
  110.      * feature:
  111.      *  @li @p ApplicationSide: the application will do page selection
  112.      *  @li @p SystemSide: page selection will be left to the print system, if available (default)
  113.      *
  114.      * @see setPageSelection(), pageSelection()
  115.      */
  116.     enum PageSelectionType { ApplicationSide = 0x01, SystemSide = 0x02 };
  117.     /**
  118.      * Defines the type of the application, this affects the GUI of the print dialog:
  119.      *  @li @p Dialog: print dialog used in an application (default)
  120.      *  @li @p StandAlone: print dialog used as a standalone widget
  121.      *  @li @p StandAlonePersistent: print dialog used as standalone widget, but persistent (do not use)
  122.      *
  123.      * @internal
  124.      * @see setApplicationType(), applicationType()
  125.      */
  126.     enum ApplicationType { Dialog = 0x00, StandAlone = 0x01, StandAlonePersistent = 0x02 };
  127.  
  128.     // QPrinter extension
  129.     /**
  130.      * Defines the page set to print:
  131.      *  @li @p AllPages: all pages
  132.      *  @li @p OddPages: only odd pages
  133.      *  @li @p EvenPages: only even pages
  134.      *
  135.      * @see pageSet()
  136.      */
  137.     enum PageSetType { AllPages = 0x00, OddPages = 0x01, EvenPages = 0x02 };
  138.     /**
  139.      * Defines the collate property of the printer (if supported by the print system):
  140.      *  @li @p Collate: copies collated (1-2-3-..., 1-2-3-...)
  141.      *  @li @p Uncollate: copies uncollated (1-1-..., 2-2-..., 3-3-...)
  142.      *
  143.      * @see setCollate(), collate()
  144.      */
  145.     enum CollateType { Collate = 0x00, Uncollate = 0x01 };
  146.  
  147.     // from QPrinter class
  148.     /**
  149.      * Defines the color mode of the printer
  150.      * @see QPrinter::ColorMode
  151.      */
  152.     enum ColorMode { GrayScale = QPrinter::GrayScale, Color = QPrinter::Color };
  153.     /**
  154.      * Defines the orientation of the paper
  155.      * @see QPrinter::Orientation
  156.      */
  157.     enum Orientation { Portrait = QPrinter::Portrait, Landscape = QPrinter::Landscape };
  158.     /**
  159.      * Defines the page order of the print job
  160.      * @see QPrinter::PageOrder
  161.      */
  162.     enum PageOrder { FirstPageFirst = QPrinter::FirstPageFirst, LastPageFirst = QPrinter::LastPageFirst };
  163.     /**
  164.      * Defines the paper size to use
  165.      * @see QPrinter::PageSize
  166.      */
  167.     enum PageSize
  168.     {
  169.         A4 = QPrinter::A4,
  170.         B5 = QPrinter::B5,
  171.         Letter = QPrinter::Letter,
  172.         Legal = QPrinter::Legal,
  173.         Executive = QPrinter::Executive,
  174.         A0 = QPrinter::A0,
  175.         A1 = QPrinter::A1,
  176.         A2 = QPrinter::A2,
  177.         A3 = QPrinter::A3,
  178.         A5 = QPrinter::A5,
  179.         A6 = QPrinter::A6,
  180.         A7 = QPrinter::A7,
  181.         A8 = QPrinter::A8,
  182.         A9 = QPrinter::A9,
  183.         B0 = QPrinter::B0,
  184.         B1 = QPrinter::B1,
  185.         B10 = QPrinter::B10,
  186.         B2 = QPrinter::B2,
  187.         B3 = QPrinter::B3,
  188.         B4 = QPrinter::B4,
  189.         B6 = QPrinter::B6,
  190.         B7 = QPrinter::B7,
  191.         B8 = QPrinter::B8,
  192.         B9 = QPrinter::B9,
  193.         C5E = QPrinter::C5E,
  194.         Comm10E = QPrinter::Comm10E,
  195.         DLE = QPrinter::DLE,
  196.         Folio = QPrinter::Folio,
  197.         Ledger = QPrinter::Ledger,
  198.         Tabloid = QPrinter::Tabloid,
  199.         NPageSize = QPrinter::NPageSize
  200.     };
  201.  
  202.     // constructors / destructor
  203.     /**
  204.      * Constructor. This also restores/saves the state from a previous KPrinter object created within
  205.      * the same application run, if @p restore is true. Setting @p restore to false may
  206.      * be useful if you want an independent/clean KPrinter object.
  207.      * @param restore if true, options will be restored/saved between successive KPrinter objects
  208.      * @param m the mode to establish the KPrinter in (see QPrinter::PrinterMode)
  209.      */
  210.     KPrinter(bool restore = true, QPrinter::PrinterMode m = QPrinter::ScreenResolution );
  211.     /**
  212.      * Destructor. This also saves the current KPrinter state for future printing.
  213.      */
  214.     ~KPrinter();
  215.  
  216.     // QPrinter interface (+ some extensions)
  217.     /**
  218.      * See QPrinter::newPage().
  219.      */
  220.     bool newPage();
  221.     /**
  222.      * See QPrinter::abort().
  223.      */
  224.     bool abort();
  225.     /**
  226.      * See QPrinter::aborted(.)
  227.      */
  228.     bool aborted() const;
  229.     /**
  230.      * See QPrinter::outputToFile().
  231.      */
  232.     bool outputToFile() const;
  233.     /**
  234.      * See QPrinter::setOutputToFile().
  235.      */
  236.     void setOutputToFile(bool);
  237.     /**
  238.      * See QPrinter::outputFileName().
  239.      */
  240.     QString outputFileName() const;
  241.     /**
  242.      * See QPrinter::setOutputFileName().
  243.      */
  244.     void setOutputFileName(const QString&);
  245.     /**
  246.      * See QPrinter::docName().
  247.      */
  248.     QString docName() const;
  249.     /**
  250.      * See QPrinter::setDocName().
  251.      */
  252.     void setDocName(const QString&);
  253.     /**
  254.      * See QPrinter::creator().
  255.      */
  256.     QString creator() const;
  257.     /**
  258.      * See QPrinter::setCreator().
  259.      */
  260.     void setCreator(const QString&);
  261.     /**
  262.      * See QPrinter::fullPage().
  263.      */
  264.     bool fullPage() const;
  265.     /**
  266.      * See QPrinter::setFullPage().
  267.      */
  268.     void setFullPage(bool);
  269.     /**
  270.      * See QPrinter::colorMode().
  271.      */
  272.     ColorMode colorMode() const;
  273.     /**
  274.      * See QPrinter::setColorMode().
  275.      */
  276.     void setColorMode(ColorMode);
  277.     /**
  278.      * See QPrinter::numCopies().
  279.      */
  280.     int numCopies() const;
  281.     /**
  282.      * See QPrinter::setNumCopies().
  283.      */
  284.     void setNumCopies(int n);
  285.     /**
  286.      * See QPrinter::orientation().
  287.      */
  288.     Orientation orientation() const;
  289.     /**
  290.      * See QPrinter::setOrientation().
  291.      */
  292.     void setOrientation(Orientation);
  293.     /**
  294.      * See QPrinter::pageOrder().
  295.      */
  296.     PageOrder pageOrder() const;
  297.     /**
  298.      * See QPrinter::setPageOrder().
  299.      */
  300.     void setPageOrder(PageOrder);
  301.     /**
  302.      * Returns the collate status of the current KPrinter.
  303.      */
  304.     CollateType collate() const;
  305.     /**
  306.      * Sets the collate status for the current KPrinter to @p type.
  307.      */
  308.     void setCollate(CollateType type);
  309.     /**
  310.      * See QPrinter::minPage().
  311.      */
  312.     int minPage() const;
  313.     /**
  314.      * See QPrinter::maxPage().
  315.      */
  316.     int maxPage() const;
  317.     /**
  318.      * See QPrinter::setMinMax().
  319.      */
  320.     void setMinMax(int, int);
  321.     /**
  322.      * Returns the first page to be printed.
  323.          * @deprecated Applications
  324.      * should use pageList() instead, which takes into account all options: collate,
  325.      * page order, ranges, page set, ...
  326.      *
  327.      * @see pageList()
  328.      */
  329.     int fromPage() const KDE_DEPRECATED;
  330.     /**
  331.      * Returns the last page to be printed.
  332.          * @deprecated Applications
  333.      * should use pageList() instead, which takes into account all options: collate,
  334.      * page order, ranges, page set, ...
  335.      *
  336.      * @see pageList()
  337.      */
  338.     int toPage() const;
  339.     /**
  340.      * Sets the first and last page to be printed. See QPrinter::setFromTo().
  341.      */
  342.     void setFromTo(int, int);
  343.     /**
  344.      * See QPrinter::pageSize().
  345.      */
  346.     PageSize pageSize() const;
  347.     /**
  348.      * See QPrinter::setPageSize().
  349.      */
  350.     void setPageSize(PageSize);
  351.     /**
  352.      * See QPrinter::printerName().
  353.      */
  354.     QString printerName() const;
  355.     /**
  356.      * See QPrinter::setPrinterName().
  357.      */
  358.     void setPrinterName(const QString&);
  359.     /**
  360.      * Returns the print program as set by setPrintProgram() or by the print dialog
  361.      * if a special printer has been selected.
  362.      * @return the print command line
  363.      * @see setPrintProgram()
  364.      */
  365.     QString printProgram() const;
  366.     /**
  367.      * Sets the command line to use when printing. This function is useful
  368.      * when using a KPrinter object without the print dialog, to control what
  369.      * to print and how to do it. The command line may contain the following
  370.      * tags:
  371.      * @li %in : the input file to the print program. It is required and automatically
  372.      *           appended at the end of the command line if not present.
  373.      * @li %out : the output file. Use this tag in conjunction with setOutputToFile()
  374.      *            and setOutputFileName()
  375.      * @li %psl : the page size in lower case. This may be useful with some
  376.      *            programs like gs.
  377.      * \code
  378.      * void createPNGOutputFile(const QString& filename)
  379.      * {
  380.      *   // use a clean KPrinter object
  381.      *   KPrinter prt(false);
  382.      *
  383.      *   prt.setOutputToFile( true );
  384.      *   prt.setOutputFileName( filename );
  385.      *   prt.setPrintProgram( "gs -sDEVICE=png256 -sPAPERSIZE=%psl -sOutputFile=%out %in" );
  386.      *
  387.      *   QPainter painter( &prt );
  388.      *   doPaint( &painter );
  389.      * }
  390.      * \endcode
  391.      * @param cmd the print command line (containing at least the @p %in tag)
  392.      * @see printProgram()
  393.      */
  394.     void setPrintProgram(const QString& cmd);
  395.     /**
  396.      * See QPrinter::printerSelectionOption(). Unused.
  397.      */
  398.     QString printerSelectionOption() const;
  399.     /**
  400.      * See QPrinter::setPrinterSelectionOption(). Unused
  401.      */
  402.     void setPrinterSelectionOption(const QString&);
  403.     /**
  404.      * Returns the current page number.
  405.      * @see setCurrentPage()
  406.      */
  407.     int currentPage() const;
  408.     /**
  409.      * Sets the current page number. This page number will be used if the user
  410.      * selected "current page" in the print dialog. This option will only be
  411.      * enabled if the application does page selection itself and the application
  412.      * has called setCurrentPage() before opening the print dialog:
  413.      * \code
  414.      * MyClass::MyClass()
  415.      * {
  416.      *   // declares my application able to do page selection
  417.      *   KPrinter::setPageSelection( KPrinter::ApplicationSide );
  418.      * }
  419.      *
  420.      * void MyClass::doPrint()
  421.      * {
  422.      *   KPrinter printer;
  423.      *
  424.      *   printer.setCurrentPage( mycurrentpage );
  425.      *   if ( printer.setup( this ) )
  426.      *   {
  427.      *     QValueList<int> pages = printer.pageList();
  428.      *     // print the pages
  429.      *     ...
  430.      *   }
  431.      * }
  432.      * \endcode
  433.      * @param p the current page number (starting from 1)
  434.      */
  435.     void setCurrentPage(int p = 0);
  436.     /**
  437.      * Returns the page set of the current KPrinter object.
  438.      */
  439.     PageSetType pageSet() const;
  440.     /**
  441.      * Sets up the KPrinter object using the print dialog, returns true if the user clicked OK.
  442.      * @param parent the parent widget to use for the print dialog
  443.      * @param caption the caption to use in the print dialog
  444.      * @param forceExpand force the expansion of the dialog (the show/hide button will be hidden)
  445.      * @returns boolean value corresponding to the button clicked by the user
  446.      */
  447.     bool setup(QWidget *parent = 0, const QString& caption = QString::null, bool forceExpand = false);
  448.     /**
  449.      * See QPrinter::margins().
  450.      */
  451.     QSize margins() const;
  452.     /**
  453.      * Not used yet.
  454.      */
  455.     void setMargins(QSize m);
  456.     /**
  457.      * Returns the page size in dot unit ( 1 dot = 1/72th in ). This method is intended for
  458.      * internal use, if you want to access actual page size, use a QPaintDeviceMetrics object
  459.      * instead. Note that the size returned by this method does not take resolution into
  460.      * account, and that it can returns invalid size if no page metric was found in the printer
  461.      * driver. DO NOT USE, WILL BE REMOVED.
  462.      * @see setRealPageSize
  463.      * @obsolete
  464.      */
  465.     QSize realPageSize() const;
  466.     /**
  467.      * DO NOT USE, WILL BE REMOVED.
  468.      * @obsolete
  469.      */
  470.     void setRealPageSize( QSize p );
  471.     /**
  472.      * DO NOT USE, WILL BE REMOVED.
  473.      * @obsolete
  474.      */
  475.     void setRealDrawableArea( const QRect& r );
  476.     /**
  477.      * DO NOT USE, WILL BE REMOVED.
  478.      * @obsolete
  479.      */
  480.     QRect realDrawableArea() const;
  481.  
  482.     void margins( uint *top, uint *left, uint *bottom, uint *right ) const;
  483.     void setMargins( uint top, uint left, uint bottom, uint right );
  484.  
  485.     /**
  486.      * Returns the page list to be printed, correpsonding to the options selected by the user. This
  487.      * takes into account collate, page order, page set, ranges, ... This is useful when the
  488.      * application does page selection itself.
  489.      * @see setCurrentPage()
  490.      */
  491.     QValueList<int> pageList() const;
  492.     /**
  493.      * Sets the KPrinter object to preview mode if @p on is true. In this mode, nothing will be
  494.      * printed but only a preview dialog will be popped up with the single "Close" action. Using
  495.      * this mode, any application can easily implement a preview action:
  496.      * \code
  497.      * void MyClass:doPreview()
  498.      * {
  499.      *   // use a "clean" KPrinter object (independent from previous print jobs),
  500.      *   // this is not necessary, it depends on the application
  501.      *   KPrinter prt( false );
  502.      *   prt.setPreviewOnly( true );
  503.      *
  504.      *   QPainter painter( &prt );
  505.      *   doPrint( &painter );
  506.      * }
  507.      * \endcode
  508.      * @param on the preview-only state
  509.      * @see previewOnly()
  510.      */
  511.     void setPreviewOnly(bool on);
  512.     /**
  513.      * Returns the preview-only state for this KPrinter object.
  514.      * @see setPreviewOnly()
  515.      */
  516.     bool previewOnly() const;
  517.     /**
  518.      * Set the resolution of the current KPrinter object. The resolution is given in DPI. This
  519.      * resolution mainly affects the accuracy for object positionning on the paint device, and
  520.      * does not influence the real resolution that will be used by the printer (this should be
  521.      * set in the driver settings). The resolution is usually defined in the constructor.
  522.      * @param dpi the resolution in DPI
  523.      * @see KPrinter(), resolution()
  524.      */
  525.     void setResolution(int dpi);
  526.     /**
  527.      * Resturns the resolution of the current KPrinter object. The resolution is given in DPI.
  528.      * @returns resolution in DPI
  529.      * @see setResolution(), KPrinter()
  530.      */
  531.     int resolution() const;
  532.  
  533.     /**
  534.      * Define the KPrinter object to use the actual printer resolution. Under some print systems
  535.      * (CUPS, Foomatic, PostScript printers), it is possible to know the actual resolution that
  536.      * is used by the printer, as selected by the user in the driver settings. If @p on is true,
  537.      * this KPrinter object will use the actual printer resolution if it is able to extract it.
  538.      * If nothing can be found, the default resolution will be the one defined by the PrinterMode
  539.      * argument used in the KPrinter constructor, or set explicitly by setResolution().
  540.      * @param on true if the KPrinter object should use the actual printer resolution
  541.      * @see resolution(), setResolution()
  542.      */
  543.     void setUsePrinterResolution( bool on );
  544.  
  545.     /**
  546.      * For internal use only.
  547.      */
  548.     KPrinterImpl* implementation() const;
  549.     /**
  550.      * Prints the files given in argument. This will first filter the files accorsing to the filtering
  551.      * options selected by the user in the print dialog, then send the filtered files to the printer
  552.      * with the print options selected. This function is called automatically when calling
  553.      * QPainter::end() for a painter object constructed on KPrinter. In normal use, you don't need
  554.      * this use this function explicitly.
  555.      */
  556.     bool printFiles(const QStringList& files, bool removeafter = false, bool startviewer = true);
  557.  
  558.     /**
  559.      * Adds a customized page to the print dialog. The pages will appear in a tab widget in the
  560.      * bottom half of the dialog, along with the standard "Copies" page. The page must be created
  561.      * and added each time you want open a print dialog with setup(). If you correctly
  562.      * reimplemented KPrintDialogPage::setOptions(), the settings will be restored from call
  563.      * to call, you don't have to worry about state saving/restoration.
  564.      * @param _page the page to add
  565.      * @see KPrintDialogPage::setOptions()
  566.      */
  567.     static void addDialogPage(KPrintDialogPage* _page);
  568.     /**
  569.      * Sets the page selection mode of the application. If needed, call this method somewhere at
  570.      * the beginning of your code. The default value is @p SystemSide.
  571.      * @param _mode the mode for the application
  572.      * @see pageSelection()
  573.      */
  574.     static void setPageSelection(PageSelectionType _mode);
  575.     /**
  576.      * Returns the page selection mode of the current application.
  577.      * @returns the page selection mode
  578.      * @see setPageSelection()
  579.      */
  580.     static PageSelectionType pageSelection();
  581.     /**
  582.      * Sets the application type concerning the print dialog. You probably don't want to use it.
  583.      * For internal use only.
  584.      * @param type the type for this application
  585.      * @see applicationType()
  586.      */
  587.     static void setApplicationType(ApplicationType type);
  588.     /**
  589.      * Returns the application type concerning the print dialog. For internal use only.
  590.      * @returns the type for the current application
  591.      * @see setApplicationType()
  592.      */
  593.     static ApplicationType applicationType();
  594.     /**
  595.      * Adds a standard page to the print dialog. This is not useful yet as there's only one
  596.      * standard page defines @p CopiesPage.
  597.      * @param p the page identifier
  598.      * @see StandardPageType
  599.      */
  600.     static void addStandardPage(int p);
  601.     /**
  602.      * Removes a standard page from the print dialog. If your application doesn't want a
  603.      * standard page in the dialog, simply call this method with the correct identifier.
  604.      * By default, the print dialog includes the @p CopiesPage page.
  605.      * @param p the page identifier
  606.      * @see StandardPageType
  607.      */
  608.     static void removeStandardPage(int p);
  609.     /**
  610.      * Starts the add printer wizard. This utility function allows any application for
  611.      * adding a printer using the KDEPrint powerful wizard.
  612.      * @param parent the parent widget for the wizard
  613.      * @returns 1: success, 0: cancel, -1: error
  614.      */
  615.     //static int addPrinterWizard(QWidget *parent = 0);
  616.  
  617.     /**
  618.      * The KPrinter object stores all its settings in an internal QMap structure on
  619.      * QString. This allows to store any property. This method allows an application to access
  620.      * any print option from the KPrinter object, using the option name. For example if your
  621.      * application add a customized page to the print dialog, this page will saves its settings
  622.      * into the KPrinter object using this QMap<QString,QString> structure. After showing the
  623.      * print dialog, your application can then access these options using this method. The
  624.      * custom option name should follow the form "kde-appname-optionname".
  625.      * \code
  626.      * void MyClass::doPrint()
  627.      * {
  628.      *   KPrinter prt;
  629.      *
  630.      *   // add my custom page
  631.      *   prt.addDialogPage( new MyDialogPage() );
  632.      *
  633.      *   // open print dialog
  634.      *   if ( prt.setup( this ) )
  635.      *   {
  636.      *      QString fntname = prt.option( "kde-myapp-fontname" );
  637.      *      ...
  638.      *      do_something;
  639.      *      ...
  640.      *   }
  641.      * }
  642.      * \endcode
  643.      * @param key the option name (key)
  644.      * @returns the option value correponding to the key, or QString::null
  645.      * @see KPrintDialogPage, setOption, options(), setOptions()
  646.      */
  647.     const QString& option(const QString& key) const;
  648.     /**
  649.      * Adds or modifies an option in the KPrinter object. You probably don't need to use this function
  650.      * explicitly. This will be done implicitely for example when reimplementing
  651.      * KPrintDialogPage::getOptions().
  652.      * @param key the option name
  653.      * @param value the option value
  654.      * @see option(), KPrintDialogPage
  655.      */
  656.     void setOption(const QString& key, const QString& value);
  657.     /**
  658.      * Returns the complete set of print options from the KPrinter object. For internal use.
  659.      * @returns the option set as a QMap object
  660.      */
  661.     const QMap<QString,QString>& options() const;
  662.     /**
  663.      * Sets the option set in one operation. This method has some side effects like merging
  664.      * the internal map with the one given in argument, but only for option in the form
  665.      * "kde-...". For internal use only.
  666.      * @param opts the option set to be merged in the KPrinter object
  667.      */
  668.     void setOptions(const QMap<QString,QString>& opts);
  669.     /**
  670.      * For internal use only. Does a similar job as setOption(), except that all possible
  671.      * internal printers are initialized with the option if it has the form "kde-...".
  672.      * @param opts the option set
  673.      * @see setOptions()
  674.      */
  675.     void initOptions(const QMap<QString,QString>& opts);
  676.  
  677.     /**
  678.      * Returns the search name of the printer selected by the user. Each printer is identified by
  679.      * a unique name. This method is mainly used for state restoration. For internal use.
  680.      * @returns the unique printer search name
  681.      * @see setSearchName
  682.      */
  683.     QString searchName() const;
  684.     /**
  685.      * Sets the search name of the KPrinter object. For internal use.
  686.      * @param n the unique printer search name
  687.      * @see searchName()
  688.      */
  689.     void setSearchName(const QString& n);
  690.     /**
  691.      * Returns the last error message issued by the print system. Unimplemented yet.
  692.      * @returns the last error message
  693.      */
  694.     QString errorMessage() const;
  695.     /**
  696.      * Sets the last error message. For internal use.
  697.      * @param msg the error message
  698.      */
  699.     void setErrorMessage(const QString& msg);
  700.     /**
  701.      * Configure the KPrinter object to be used with the printer named
  702.      * @p prname. After the call, the KPrinter object can be used without
  703.      * the need to call the print dialog. If @p prname is empty, then the
  704.      * KPrinter object is configured for the default printer. If @p prname
  705.      * corresponds to a pseudo-printer which needs an output file, a file
  706.      * dialog will be used. In that case, providing a parent widget for
  707.      * that dialog in @p parent may be useful.
  708.      * @param prname the name of the printer for which the KPrinter object
  709.      * has to be configured
  710.      * @param parent a parent widget, used a parent for a file dialog
  711.      * @returns boolean flag: if false, the KPrinter has not been correctly
  712.      * set up, and the application shouldn't use it to print. This may
  713.      * happen if the printer named @p prname has not been found or if the
  714.      * user clicked "Cancel" in the file dialog.
  715.      * @see setup()
  716.      */
  717.     bool autoConfigure(const QString& prname = QString::null, QWidget *parent = 0);
  718.     /**
  719.      * Set the default document filename. This filename will be used as the
  720.      * default basename for the output file, instead of the default "print".
  721.      * For example, by using setDocFileName("my_document"), the default
  722.      * output file will be $HOME/my_document.ps.
  723.      * @param filename the default document basename to use
  724.      * @see docFileName()
  725.      */
  726.     void setDocFileName(const QString& filename);
  727.     /**
  728.      * Get the default document filename, that is the default basename used for
  729.      * the output file.
  730.      * @returns the default document basename
  731.      * @see setDocFileName()
  732.      */
  733.     QString docFileName() const;
  734.     /**
  735.      * Set the default document directory. This directory will be used as
  736.      * the default location for any output file. If not set, $HOME directory
  737.      * is used instead.
  738.      * @param dir the new default output directory
  739.      * @see docDirectory()
  740.      */
  741.     void setDocDirectory( const QString& dir );
  742.     /**
  743.      * Get the default document directory, that is the directory used for
  744.      * any output file. By default, it is the $HOME directory.
  745.      * @returns the default output directory
  746.      * @see setDocDirectory
  747.      */
  748.     QString docDirectory() const;
  749.  
  750. protected:
  751.     virtual bool cmd(int, QPainter*, QPDevCmdParam*);
  752.     virtual int metric(int) const;
  753.     void translateQtOptions();
  754.     void loadSettings();
  755.     void saveSettings();
  756.     void preparePrinting();
  757.     void finishPrinting();
  758.     void reload();
  759.     void init(bool restore = true, QPrinter::PrinterMode m = QPrinter::ScreenResolution);
  760.     bool doPreview(const QString& file);
  761.     void setRealPageSize(DrPageSize* p);
  762.     void setOption( const QString& key, const QString& value, bool broadcast );
  763.  
  764. protected:
  765.     KPrinterPrivate        *d;
  766. };
  767.  
  768. //**************************************************************************************
  769.  
  770. // Utility functions
  771.  
  772. KDEPRINT_EXPORT KPrinter::PageSize pageNameToPageSize(const QString& name);
  773. KDEPRINT_EXPORT const char* pageSizeToPageName(KPrinter::PageSize s);
  774. /**
  775.  * DO NOT USE, WILL BE REMOVED.
  776.  * @obsolete
  777.  */
  778. QSize rangeToSize( const QString& );
  779.  
  780. #endif
  781.